# YAML 插件

import { SourceCode } from 'rspress/theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-yaml" />

用于引用 YAML 文件，并将其转换为 JavaScript 对象。

:::tip
[YAML](https://yaml.org/) 是一种数据序列化语言，通常用于编写配置文件。
:::

## 快速开始

### 安装插件

你可以通过如下的命令安装插件:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-yaml -D" />

### 注册插件

你可以在 `rsbuild.config.ts` 文件中注册插件：

```ts title="rsbuild.config.ts"
import { pluginYaml } from '@rsbuild/plugin-yaml';

export default {
  plugins: [pluginYaml()],
};
```

## 示例

比如项目中有以下代码：

```yaml title="example.yaml"
---
hello: world
foo:
  bar: baz
```

在使用 YAML 插件后，你可以通过如下方式引用：

```js
import example from './example.yaml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```

## 类型声明

当你在 TypeScript 代码中引用 YAML 文件时，请在项目中创建 `src/env.d.ts` 文件，并添加相应的类型声明。

- 方法一：如果项目里安装了 `@rsbuild/core` 包，你可以直接引用 `@rsbuild/core` 提供的类型声明：

```ts title="src/env.d.ts"
/// <reference types="@rsbuild/core/types" />
```

- 方法二：手动添加需要的类型声明：

```ts title="src/env.d.ts"
declare module '*.yaml' {
  const content: Record<string, any>;
  export default content;
}
declare module '*.yml' {
  const content: Record<string, any>;
  export default content;
}
```
